The module docstring references docs/byte-layout-spec.md, but there is no docs/ directory (and no file with that name) in this repository. This makes the reference non-actionable for maintainers; please either add the spec file at that path or update the reference to the correct location (e.g., a README section or an in-repo spec file).

Good catch — the spec lives in the Rust repo, not here. Fixed the docstring to reference nauticalab/starfix docs/byte-layout-spec.md instead of a non-existent local path.

Struct null propagation seems incomplete at the type-decomposition stage: when a struct field is nullable, all descendant entries become effectively nullable (struct validity AND child validity per spec 3.5). Here _extract_type_entries() recurses into children using only child.nullable, so non-nullable children of a nullable struct will not get a null_bits buffer and their propagated null positions won’t be represented in the final digest (only skipped in data hashing). Consider recursing with child.nullable or nullable so child entries include null_bits whenever any ancestor struct is nullable.

This is intentional and matches both the spec and the Rust implementation.

The spec (Section 3.5, Example M) says struct-level nulls are AND-propagated at traversal time, not at entry-creation time. Non-nullable children of a nullable struct get data-only entries (no null_bits). The null propagation is handled by _traverse_struct which passes combined ancestor nulls down — _traverse_leaf then skips null rows when hashing data bytes.

From spec Example M:

Entry "a" (Int32, non-nullable → data-only): Struct nulls propagated: rows 0, 2 valid → data: [10, 30]

The Rust extract_type_entries also passes child_field.is_nullable() (not child.nullable || parent.nullable) — see arrow_digester_core.rs:934. All 126 parity tests (including nullable struct cases like r2_nullable_struct_batch and r2_nested_nullable_inner_struct) confirm this produces correct hashes.

_normalize_data_type()’s Map handling drops important information and may produce an incorrect canonical type: it only normalizes the key field (not the item/value field), it doesn’t preserve keys_sorted, and it reconstructs the map using pa.map_() defaults. If maps are intended to be supported, this should normalize both key/item fields and carry over keys_sorted to avoid schema/type hashes diverging from Arrow/Rust for map schemas.

Good catch — the item field was not being normalized. Fixed to normalize both key and item fields, and preserve keys_sorted. Map types are not yet exercised by the test suite, but this is the correct normalization per the spec.

_extract_type_entries() treats structs as “transparent” and only uses each child field’s declared nullable to decide whether to allocate null_bits. If the parent struct itself is nullable, nulls must still be AND-propagated to descendants (spec 3.5), which requires descendant entries to include validity (null_bits) even when the child field is declared non-nullable. As written, nullable structs with non-nullable children will lose null position information (children have null_bits=None). Consider propagating nullable into the recursive calls (e.g., pass nullable or child.nullable) so descendants can record effective validity.

Same point as the earlier review — addressed in the reply there. This is intentional per the spec: struct null propagation happens at traversal time (via _traverse_struct passing combined ancestor nulls), not at entry-creation time. Non-nullable children of a nullable struct get data-only entries. See spec Example M and Rust extract_type_entries at line 934. Verified by 126 parity tests.

pytest is imported but not used in this test module. Removing unused imports helps keep the test code clean and avoids lint warnings in environments that enforce them.

This was already removed in a subsequent commit — neither test_golden_parity.py nor test_golden_parity_r2.py imports pytest in the current version.

pytest is imported but not used in this test module. Consider removing it to avoid unused-import warnings in linted environments.

Same as above — pytest is not imported in the current version of this file.